home *** CD-ROM | disk | FTP | other *** search
/ Spidla DivX / DivX.bin / FLAC 1.1.0 / include / FLAC / seekable_stream_decoder.h < prev    next >
Encoding:
C/C++ Source or Header  |  2003-01-01  |  35.0 KB  |  909 lines

  1. /* libFLAC - Free Lossless Audio Codec library
  2.  * Copyright (C) 2000,2001,2002,2003  Josh Coalson
  3.  *
  4.  * This library is free software; you can redistribute it and/or
  5.  * modify it under the terms of the GNU Library General Public
  6.  * License as published by the Free Software Foundation; either
  7.  * version 2 of the License, or (at your option) any later version.
  8.  *
  9.  * This library is distributed in the hope that it will be useful,
  10.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.  * Library General Public License for more details.
  13.  *
  14.  * You should have received a copy of the GNU Library General Public
  15.  * License along with this library; if not, write to the
  16.  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17.  * Boston, MA  02111-1307, USA.
  18.  */
  19.  
  20. #ifndef FLAC__SEEKABLE_STREAM_DECODER_H
  21. #define FLAC__SEEKABLE_STREAM_DECODER_H
  22.  
  23. #include "export.h"
  24. #include "stream_decoder.h"
  25.  
  26. #ifdef __cplusplus
  27. extern "C" {
  28. #endif
  29.  
  30.  
  31. /** \file include/FLAC/seekable_stream_decoder.h
  32.  *
  33.  *  \brief
  34.  *  This module contains the functions which implement the seekable stream
  35.  *  decoder.
  36.  *
  37.  *  See the detailed documentation in the
  38.  *  \link flac_seekable_stream_decoder seekable stream decoder \endlink module.
  39.  */
  40.  
  41. /** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface
  42.  *  \ingroup flac_decoder
  43.  *
  44.  *  \brief
  45.  *  This module contains the functions which implement the seekable stream
  46.  *  decoder.
  47.  *
  48.  * The basic usage of this decoder is as follows:
  49.  * - The program creates an instance of a decoder using
  50.  *   FLAC__seekable_stream_decoder_new().
  51.  * - The program overrides the default settings and sets callbacks for
  52.  *   reading, writing, seeking, error reporting, and metadata reporting
  53.  *   using FLAC__seekable_stream_decoder_set_*() functions.
  54.  * - The program initializes the instance to validate the settings and
  55.  *   prepare for decoding using FLAC__seekable_stream_decoder_init().
  56.  * - The program calls the FLAC__seekable_stream_decoder_process_*()
  57.  *   functions to decode data, which subsequently calls the callbacks.
  58.  * - The program finishes the decoding with
  59.  *   FLAC__seekable_stream_decoder_finish(), which flushes the input and
  60.  *   output and resets the decoder to the uninitialized state.
  61.  * - The instance may be used again or deleted with
  62.  *   FLAC__seekable_stream_decoder_delete().
  63.  *
  64.  * The seekable stream decoder is a wrapper around the
  65.  * \link flac_stream_decoder stream decoder \endlink which also provides
  66.  * seeking capability.  In addition to the Read/Write/Metadata/Error
  67.  * callbacks of the stream decoder, the user must also provide the following:
  68.  *
  69.  * - Seek callback - This function will be called when the decoder wants to
  70.  *   seek to an absolute position in the stream.
  71.  * - Tell callback - This function will be called when the decoder wants to
  72.  *   know the current absolute position of the stream.
  73.  * - Length callback - This function will be called when the decoder wants
  74.  *   to know length of the stream.  The seeking algorithm currently requires
  75.  *   that the overall stream length be known.
  76.  * - EOF callback - This function will be called when the decoder wants to
  77.  *   know if it is at the end of the stream.  This could be synthesized from
  78.  *   the tell and length callbacks but it may be more expensive that way, so
  79.  *   there is a separate callback for it.
  80.  *
  81.  * Seeking is exposed through the
  82.  * FLAC__seekable_stream_decoder_seek_absolute() method.  At any point after
  83.  * the seekable stream decoder has been initialized, the user can call this
  84.  * function to seek to an exact sample within the stream.  Subsequently, the
  85.  * first time the write callback is called it will be passed a (possibly
  86.  * partial) block starting at that sample.
  87.  *
  88.  * The seekable stream decoder also provides MD5 signature checking.  If
  89.  * this is turned on before initialization,
  90.  * FLAC__seekable_stream_decoder_finish() will report when the decoded MD5
  91.  * signature does not match the one stored in the STREAMINFO block.  MD5
  92.  * checking is automatically turned off (until the next
  93.  * FLAC__seekable_stream_decoder_reset()) if there is no signature in the
  94.  * STREAMINFO block or when a seek is attempted.
  95.  *
  96.  * Make sure to read the detailed description of the
  97.  * \link flac_stream_decoder stream decoder module \endlink since the
  98.  * seekable stream decoder inherits much of its behavior.
  99.  *
  100.  * \note
  101.  * The "set" functions may only be called when the decoder is in the
  102.  * state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after
  103.  * FLAC__seekable_stream_decoder_new() or
  104.  * FLAC__seekable_stream_decoder_finish(), but before
  105.  * FLAC__seekable_stream_decoder_init().  If this is the case they will
  106.  * return \c true, otherwise \c false.
  107.  *
  108.  * \note
  109.  * FLAC__stream_decoder_finish() resets all settings to the constructor
  110.  * defaults, including the callbacks.
  111.  *
  112.  * \{
  113.  */
  114.  
  115.  
  116. /** State values for a FLAC__SeekableStreamDecoder
  117.  *
  118.  *  The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state().
  119.  */
  120. typedef enum {
  121.  
  122.     FLAC__SEEKABLE_STREAM_DECODER_OK = 0,
  123.     /**< The decoder is in the normal OK state. */
  124.  
  125.     FLAC__SEEKABLE_STREAM_DECODER_SEEKING,
  126.     /**< The decoder is in the process of seeking. */
  127.  
  128.     FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
  129.     /**< The decoder has reached the end of the stream. */
  130.  
  131.     FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
  132.     /**< An error occurred allocating memory. */
  133.  
  134.     FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
  135.     /**< An error occurred in the underlying stream decoder. */
  136.  
  137.     FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
  138.     /**< The read callback returned an error. */
  139.  
  140.     FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
  141.     /**< An error occurred while seeking or the seek or tell
  142.      * callback returned an error.
  143.      */
  144.  
  145.     FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
  146.     /**< FLAC__seekable_stream_decoder_init() was called when the
  147.      * decoder was already initialized, usually because
  148.      * FLAC__seekable_stream_decoder_finish() was not called.
  149.      */
  150.  
  151.     FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
  152.     /**< FLAC__seekable_stream_decoder_init() was called without all
  153.      * callbacks being set.
  154.      */
  155.  
  156.     FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
  157.     /**< The decoder is in the uninitialized state. */
  158.  
  159. } FLAC__SeekableStreamDecoderState;
  160.  
  161. /** Maps a FLAC__SeekableStreamDecoderState to a C string.
  162.  *
  163.  *  Using a FLAC__SeekableStreamDecoderState as the index to this array
  164.  *  will give the string equivalent.  The contents should not be modified.
  165.  */
  166. extern FLAC_API const char * const FLAC__SeekableStreamDecoderStateString[];
  167.  
  168.  
  169. /** Return values for the FLAC__SeekableStreamDecoder read callback.
  170.  */
  171. typedef enum {
  172.  
  173.     FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
  174.     /**< The read was OK and decoding can continue. */
  175.  
  176.     FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
  177.     /**< An unrecoverable error occurred.  The decoder will return from the process call. */
  178.  
  179. } FLAC__SeekableStreamDecoderReadStatus;
  180.  
  181. /** Maps a FLAC__SeekableStreamDecoderReadStatus to a C string.
  182.  *
  183.  *  Using a FLAC__SeekableStreamDecoderReadStatus as the index to this array
  184.  *  will give the string equivalent.  The contents should not be modified.
  185.  */
  186. extern FLAC_API const char * const FLAC__SeekableStreamDecoderReadStatusString[];
  187.  
  188.  
  189. /** Return values for the FLAC__SeekableStreamDecoder seek callback.
  190.  */
  191. typedef enum {
  192.  
  193.     FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
  194.     /**< The seek was OK and decoding can continue. */
  195.  
  196.     FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
  197.     /**< An unrecoverable error occurred.  The decoder will return from the process call. */
  198.  
  199. } FLAC__SeekableStreamDecoderSeekStatus;
  200.  
  201. /** Maps a FLAC__SeekableStreamDecoderSeekStatus to a C string.
  202.  *
  203.  *  Using a FLAC__SeekableStreamDecoderSeekStatus as the index to this array
  204.  *  will give the string equivalent.  The contents should not be modified.
  205.  */
  206. extern FLAC_API const char * const FLAC__SeekableStreamDecoderSeekStatusString[];
  207.  
  208.  
  209. /** Return values for the FLAC__SeekableStreamDecoder tell callback.
  210.  */
  211. typedef enum {
  212.  
  213.     FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
  214.     /**< The tell was OK and decoding can continue. */
  215.  
  216.     FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
  217.     /**< An unrecoverable error occurred.  The decoder will return from the process call. */
  218.  
  219. } FLAC__SeekableStreamDecoderTellStatus;
  220.  
  221. /** Maps a FLAC__SeekableStreamDecoderTellStatus to a C string.
  222.  *
  223.  *  Using a FLAC__SeekableStreamDecoderTellStatus as the index to this array
  224.  *  will give the string equivalent.  The contents should not be modified.
  225.  */
  226. extern FLAC_API const char * const FLAC__SeekableStreamDecoderTellStatusString[];
  227.  
  228.  
  229. /** Return values for the FLAC__SeekableStreamDecoder length callback.
  230.  */
  231. typedef enum {
  232.  
  233.     FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
  234.     /**< The length call was OK and decoding can continue. */
  235.  
  236.     FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
  237.     /**< An unrecoverable error occurred.  The decoder will return from the process call. */
  238.  
  239. } FLAC__SeekableStreamDecoderLengthStatus;
  240.  
  241. /** Maps a FLAC__SeekableStreamDecoderLengthStatus to a C string.
  242.  *
  243.  *  Using a FLAC__SeekableStreamDecoderLengthStatus as the index to this array
  244.  *  will give the string equivalent.  The contents should not be modified.
  245.  */
  246. extern FLAC_API const char * const FLAC__SeekableStreamDecoderLengthStatusString[];
  247.  
  248.  
  249. /***********************************************************************
  250.  *
  251.  * class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
  252.  *
  253.  ***********************************************************************/
  254.  
  255. struct FLAC__SeekableStreamDecoderProtected;
  256. struct FLAC__SeekableStreamDecoderPrivate;
  257. /** The opaque structure definition for the seekable stream decoder type.
  258.  *  See the
  259.  *  \link flac_seekable_stream_decoder seekable stream decoder module \endlink
  260.  *  for a detailed description.
  261.  */
  262. typedef struct {
  263.     struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  264.     struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
  265. } FLAC__SeekableStreamDecoder;
  266.  
  267. /** Signature for the read callback.
  268.  *  See FLAC__seekable_stream_decoder_set_read_callback()
  269.  *  and FLAC__StreamDecoderReadCallback for more info.
  270.  *
  271.  * \param  decoder  The decoder instance calling the callback.
  272.  * \param  buffer   A pointer to a location for the callee to store
  273.  *                  data to be decoded.
  274.  * \param  bytes    A pointer to the size of the buffer.
  275.  * \param  client_data  The callee's client data set through
  276.  *                      FLAC__seekable_stream_decoder_set_client_data().
  277.  * \retval FLAC__SeekableStreamDecoderReadStatus
  278.  *    The callee's return status.
  279.  */
  280. typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
  281.  
  282. /** Signature for the seek callback.
  283.  *  See FLAC__seekable_stream_decoder_set_seek_callback() for more info.
  284.  *
  285.  * \param  decoder  The decoder instance calling the callback.
  286.  * \param  absolute_byte_offset  The offset from the beginning of the stream
  287.  *                               to seek to.
  288.  * \param  client_data  The callee's client data set through
  289.  *                      FLAC__seekable_stream_decoder_set_client_data().
  290.  * \retval FLAC__SeekableStreamDecoderSeekStatus
  291.  *    The callee's return status.
  292.  */
  293. typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
  294.  
  295. /** Signature for the tell callback.
  296.  *  See FLAC__seekable_stream_decoder_set_tell_callback() for more info.
  297.  *
  298.  * \param  decoder  The decoder instance calling the callback.
  299.  * \param  absolute_byte_offset  A pointer to storage for the current offset
  300.  *                               from the beginning of the stream.
  301.  * \param  client_data  The callee's client data set through
  302.  *                      FLAC__seekable_stream_decoder_set_client_data().
  303.  * \retval FLAC__SeekableStreamDecoderTellStatus
  304.  *    The callee's return status.
  305.  */
  306. typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
  307.  
  308. /** Signature for the length callback.
  309.  *  See FLAC__seekable_stream_decoder_set_length_callback() for more info.
  310.  *
  311.  * \param  decoder  The decoder instance calling the callback.
  312.  * \param  stream_length  A pointer to storage for the length of the stream
  313.  *                        in bytes.
  314.  * \param  client_data  The callee's client data set through
  315.  *                      FLAC__seekable_stream_decoder_set_client_data().
  316.  * \retval FLAC__SeekableStreamDecoderLengthStatus
  317.  *    The callee's return status.
  318.  */
  319. typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
  320.  
  321. /** Signature for the EOF callback.
  322.  *  See FLAC__seekable_stream_decoder_set_eof_callback() for more info.
  323.  *
  324.  * \param  decoder  The decoder instance calling the callback.
  325.  * \param  client_data  The callee's client data set through
  326.  *                      FLAC__seekable_stream_decoder_set_client_data().
  327.  * \retval FLAC__bool
  328.  *    \c true if the currently at the end of the stream, else \c false.
  329.  */
  330. typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data);
  331.  
  332. /** Signature for the write callback.
  333.  *  See FLAC__seekable_stream_decoder_set_write_callback()
  334.  *  and FLAC__StreamDecoderWriteCallback for more info.
  335.  *
  336.  * \param  decoder  The decoder instance calling the callback.
  337.  * \param  frame    The description of the decoded frame.
  338.  * \param  buffer   An array of pointers to decoded channels of data.
  339.  * \param  client_data  The callee's client data set through
  340.  *                      FLAC__seekable_stream_decoder_set_client_data().
  341.  * \retval FLAC__StreamDecoderWriteStatus
  342.  *    The callee's return status.
  343.  */
  344. typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
  345.  
  346. /** Signature for the metadata callback.
  347.  *  See FLAC__seekable_stream_decoder_set_metadata_callback()
  348.  *  and FLAC__StreamDecoderMetadataCallback for more info.
  349.  *
  350.  * \param  decoder  The decoder instance calling the callback.
  351.  * \param  metadata The decoded metadata block.
  352.  * \param  client_data  The callee's client data set through
  353.  *                      FLAC__seekable_stream_decoder_set_client_data().
  354.  */
  355. typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
  356.  
  357. /** Signature for the error callback.
  358.  *  See FLAC__seekable_stream_decoder_set_error_callback()
  359.  *  and FLAC__StreamDecoderErrorCallback for more info.
  360.  *
  361.  * \param  decoder  The decoder instance calling the callback.
  362.  * \param  status   The error encountered by the decoder.
  363.  * \param  client_data  The callee's client data set through
  364.  *                      FLAC__seekable_stream_decoder_set_client_data().
  365.  */
  366. typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
  367.  
  368.  
  369. /***********************************************************************
  370.  *
  371.  * Class constructor/destructor
  372.  *
  373.  ***********************************************************************/
  374.  
  375. /** Create a new seekable stream decoder instance.  The instance is created
  376.  *  with default settings; see the individual
  377.  *  FLAC__seekable_stream_decoder_set_*() functions for each setting's
  378.  *  default.
  379.  *
  380.  * \retval FLAC__SeekableStreamDecoder*
  381.  *    \c NULL if there was an error allocating memory, else the new instance.
  382.  */
  383. FLAC_API FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new();
  384.  
  385. /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
  386.  *
  387.  * \param decoder  A pointer to an existing decoder.
  388.  * \assert
  389.  *    \code decoder != NULL \endcode
  390.  */
  391. FLAC_API void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder);
  392.  
  393.  
  394. /***********************************************************************
  395.  *
  396.  * Public class method prototypes
  397.  *
  398.  ***********************************************************************/
  399.  
  400. /** Set the "MD5 signature checking" flag.  If \c true, the decoder will
  401.  *  compute the MD5 signature of the unencoded audio data while decoding
  402.  *  and compare it to the signature from the STREAMINFO block, if it
  403.  *  exists, during FLAC__seekable_stream_decoder_finish().
  404.  *
  405.  *  MD5 signature checking will be turned off (until the next
  406.  *  FLAC__seekable_stream_decoder_reset()) if there is no signature in
  407.  *  the STREAMINFO block or when a seek is attempted.
  408.  *
  409.  * \default \c false
  410.  * \param  decoder  A decoder instance to set.
  411.  * \param  value    Flag value (see above).
  412.  * \assert
  413.  *    \code decoder != NULL \endcode
  414.  * \retval FLAC__bool
  415.  *    \c false if the decoder is already initialized, else \c true.
  416.  */
  417. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
  418.  
  419. /** Set the read callback.
  420.  *  This is inherited from FLAC__StreamDecoder; see
  421.  *  FLAC__stream_decoder_set_read_callback().
  422.  *
  423.  * \note
  424.  * The callback is mandatory and must be set before initialization.
  425.  *
  426.  * \default \c NULL
  427.  * \param  decoder  A decoder instance to set.
  428.  * \param  value    See above.
  429.  * \assert
  430.  *    \code decoder != NULL \endcode
  431.  *    \code value != NULL \endcode
  432.  * \retval FLAC__bool
  433.  *    \c false if the decoder is already initialized, else \c true.
  434.  */
  435. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadCallback value);
  436.  
  437. /** Set the seek callback.
  438.  *  The supplied function will be called when the decoder needs to seek
  439.  *  the input stream.  The decoder will pass the absolute byte offset
  440.  *  to seek to, 0 meaning the beginning of the stream.
  441.  *
  442.  * \note
  443.  * The callback is mandatory and must be set before initialization.
  444.  *
  445.  * \default \c NULL
  446.  * \param  decoder  A decoder instance to set.
  447.  * \param  value    See above.
  448.  * \assert
  449.  *    \code decoder != NULL \endcode
  450.  *    \code value != NULL \endcode
  451.  * \retval FLAC__bool
  452.  *    \c false if the decoder is already initialized, else \c true.
  453.  */
  454. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekCallback value);
  455.  
  456. /** Set the tell callback.
  457.  *  The supplied function will be called when the decoder wants to know
  458.  *  the current position of the stream.  The callback should return the
  459.  *  byte offset from the beginning of the stream.
  460.  *
  461.  * \note
  462.  * The callback is mandatory and must be set before initialization.
  463.  *
  464.  * \default \c NULL
  465.  * \param  decoder  A decoder instance to set.
  466.  * \param  value    See above.
  467.  * \assert
  468.  *    \code decoder != NULL \endcode
  469.  *    \code value != NULL \endcode
  470.  * \retval FLAC__bool
  471.  *    \c false if the decoder is already initialized, else \c true.
  472.  */
  473. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellCallback value);
  474.  
  475. /** Set the length callback.
  476.  *  The supplied function will be called when the decoder wants to know
  477.  *  the total length of the stream in bytes.
  478.  *
  479.  * \note
  480.  * The callback is mandatory and must be set before initialization.
  481.  *
  482.  * \default \c NULL
  483.  * \param  decoder  A decoder instance to set.
  484.  * \param  value    See above.
  485.  * \assert
  486.  *    \code decoder != NULL \endcode
  487.  *    \code value != NULL \endcode
  488.  * \retval FLAC__bool
  489.  *    \c false if the decoder is already initialized, else \c true.
  490.  */
  491. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthCallback value);
  492.  
  493. /** Set the eof callback.
  494.  *  The supplied function will be called when the decoder needs to know
  495.  *  if the end of the stream has been reached.
  496.  *
  497.  * \note
  498.  * The callback is mandatory and must be set before initialization.
  499.  *
  500.  * \default \c NULL
  501.  * \param  decoder  A decoder instance to set.
  502.  * \param  value    See above.
  503.  * \assert
  504.  *    \code decoder != NULL \endcode
  505.  *    \code value != NULL \endcode
  506.  * \retval FLAC__bool
  507.  *    \c false if the decoder is already initialized, else \c true.
  508.  */
  509. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value);
  510.  
  511. /** Set the write callback.
  512.  *  This is inherited from FLAC__StreamDecoder; see
  513.  *  FLAC__stream_decoder_set_write_callback().
  514.  *
  515.  * \note
  516.  * The callback is mandatory and must be set before initialization.
  517.  *
  518.  * \default \c NULL
  519.  * \param  decoder  A decoder instance to set.
  520.  * \param  value    See above.
  521.  * \assert
  522.  *    \code decoder != NULL \endcode
  523.  *    \code value != NULL \endcode
  524.  * \retval FLAC__bool
  525.  *    \c false if the decoder is already initialized, else \c true.
  526.  */
  527. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value);
  528.  
  529. /** Set the metadata callback.
  530.  *  This is inherited from FLAC__StreamDecoder; see
  531.  *  FLAC__stream_decoder_set_metadata_callback().
  532.  *
  533.  * \note
  534.  * The callback is mandatory and must be set before initialization.
  535.  *
  536.  * \default \c NULL
  537.  * \param  decoder  A decoder instance to set.
  538.  * \param  value    See above.
  539.  * \assert
  540.  *    \code decoder != NULL \endcode
  541.  *    \code value != NULL \endcode
  542.  * \retval FLAC__bool
  543.  *    \c false if the decoder is already initialized, else \c true.
  544.  */
  545. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value);
  546.  
  547. /** Set the error callback.
  548.  *  This is inherited from FLAC__StreamDecoder; see
  549.  *  FLAC__stream_decoder_set_error_callback().
  550.  *
  551.  * \note
  552.  * The callback is mandatory and must be set before initialization.
  553.  *
  554.  * \default \c NULL
  555.  * \param  decoder  A decoder instance to set.
  556.  * \param  value    See above.
  557.  * \assert
  558.  *    \code decoder != NULL \endcode
  559.  *    \code value != NULL \endcode
  560.  * \retval FLAC__bool
  561.  *    \c false if the decoder is already initialized, else \c true.
  562.  */
  563. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value);
  564.  
  565. /** Set the client data to be passed back to callbacks.
  566.  *  This value will be supplied to callbacks in their \a client_data
  567.  *  argument.
  568.  *
  569.  * \default \c NULL
  570.  * \param  decoder  A decoder instance to set.
  571.  * \param  value    See above.
  572.  * \assert
  573.  *    \code decoder != NULL \endcode
  574.  * \retval FLAC__bool
  575.  *    \c false if the decoder is already initialized, else \c true.
  576.  */
  577. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value);
  578.  
  579. /** This is inherited from FLAC__StreamDecoder; see
  580.  *  FLAC__stream_decoder_set_metadata_respond().
  581.  *
  582.  * \default By default, only the \c STREAMINFO block is returned via the
  583.  *          metadata callback.
  584.  * \param  decoder  A decoder instance to set.
  585.  * \param  type     See above.
  586.  * \assert
  587.  *    \code decoder != NULL \endcode
  588.  *    \a type is valid
  589.  * \retval FLAC__bool
  590.  *    \c false if the decoder is already initialized, else \c true.
  591.  */
  592. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
  593.  
  594. /** This is inherited from FLAC__StreamDecoder; see
  595.  *  FLAC__stream_decoder_set_metadata_respond_application().
  596.  *
  597.  * \default By default, only the \c STREAMINFO block is returned via the
  598.  *          metadata callback.
  599.  * \param  decoder  A decoder instance to set.
  600.  * \param  id       See above.
  601.  * \assert
  602.  *    \code decoder != NULL \endcode
  603.  *    \code id != NULL \endcode
  604.  * \retval FLAC__bool
  605.  *    \c false if the decoder is already initialized, else \c true.
  606.  */
  607. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
  608.  
  609. /** This is inherited from FLAC__StreamDecoder; see
  610.  *  FLAC__stream_decoder_set_metadata_respond_all().
  611.  *
  612.  * \default By default, only the \c STREAMINFO block is returned via the
  613.  *          metadata callback.
  614.  * \param  decoder  A decoder instance to set.
  615.  * \assert
  616.  *    \code decoder != NULL \endcode
  617.  * \retval FLAC__bool
  618.  *    \c false if the decoder is already initialized, else \c true.
  619.  */
  620. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_all(FLAC__SeekableStreamDecoder *decoder);
  621.  
  622. /** This is inherited from FLAC__StreamDecoder; see
  623.  *  FLAC__stream_decoder_set_metadata_ignore().
  624.  *
  625.  * \default By default, only the \c STREAMINFO block is returned via the
  626.  *          metadata callback.
  627.  * \param  decoder  A decoder instance to set.
  628.  * \param  type     See above.
  629.  * \assert
  630.  *    \code decoder != NULL \endcode
  631.  *    \a type is valid
  632.  * \retval FLAC__bool
  633.  *    \c false if the decoder is already initialized, else \c true.
  634.  */
  635. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
  636.  
  637. /** This is inherited from FLAC__StreamDecoder; see
  638.  *  FLAC__stream_decoder_set_metadata_ignore_application().
  639.  *
  640.  * \default By default, only the \c STREAMINFO block is returned via the
  641.  *          metadata callback.
  642.  * \param  decoder  A decoder instance to set.
  643.  * \param  id       See above.
  644.  * \assert
  645.  *    \code decoder != NULL \endcode
  646.  *    \code id != NULL \endcode
  647.  * \retval FLAC__bool
  648.  *    \c false if the decoder is already initialized, else \c true.
  649.  */
  650. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
  651.  
  652. /** This is inherited from FLAC__StreamDecoder; see
  653.  *  FLAC__stream_decoder_set_metadata_ignore_all().
  654.  *
  655.  * \default By default, only the \c STREAMINFO block is returned via the
  656.  *          metadata callback.
  657.  * \param  decoder  A decoder instance to set.
  658.  * \assert
  659.  *    \code decoder != NULL \endcode
  660.  * \retval FLAC__bool
  661.  *    \c false if the decoder is already initialized, else \c true.
  662.  */
  663. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder);
  664.  
  665. /** Get the current decoder state.
  666.  *
  667.  * \param  decoder  A decoder instance to query.
  668.  * \assert
  669.  *    \code decoder != NULL \endcode
  670.  * \retval FLAC__SeekableStreamDecoderState
  671.  *    The current decoder state.
  672.  */
  673. FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder);
  674.  
  675. /** Get the state of the underlying stream decoder.
  676.  *  Useful when the seekable stream decoder state is
  677.  *  \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
  678.  *
  679.  * \param  decoder  A decoder instance to query.
  680.  * \assert
  681.  *    \code decoder != NULL \endcode
  682.  * \retval FLAC__StreamDecoderState
  683.  *    The stream decoder state.
  684.  */
  685. FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state(const FLAC__SeekableStreamDecoder *decoder);
  686.  
  687. /** Get the current decoder state as a C string.
  688.  *  This version automatically resolves
  689.  *  \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR by getting the
  690.  *  stream decoder's state.
  691.  *
  692.  * \param  decoder  A decoder instance to query.
  693.  * \assert
  694.  *    \code decoder != NULL \endcode
  695.  * \retval const char *
  696.  *    The decoder state as a C string.  Do not modify the contents.
  697.  */
  698. FLAC_API const char *FLAC__seekable_stream_decoder_get_resolved_state_string(const FLAC__SeekableStreamDecoder *decoder);
  699.  
  700. /** Get the "MD5 signature checking" flag.
  701.  *  This is the value of the setting, not whether or not the decoder is
  702.  *  currently checking the MD5 (remember, it can be turned off automatically
  703.  *  by a seek).  When the decoder is reset the flag will be restored to the
  704.  *  value returned by this function.
  705.  *
  706.  * \param  decoder  A decoder instance to query.
  707.  * \assert
  708.  *    \code decoder != NULL \endcode
  709.  * \retval FLAC__bool
  710.  *    See above.
  711.  */
  712. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
  713.  
  714. /** This is inherited from FLAC__StreamDecoder; see
  715.  *  FLAC__stream_decoder_get_channels().
  716.  *
  717.  * \param  decoder  A decoder instance to query.
  718.  * \assert
  719.  *    \code decoder != NULL \endcode
  720.  * \retval unsigned
  721.  *    See above.
  722.  */
  723. FLAC_API unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder);
  724.  
  725. /** This is inherited from FLAC__StreamDecoder; see
  726.  *  FLAC__stream_decoder_get_channel_assignment().
  727.  *
  728.  * \param  decoder  A decoder instance to query.
  729.  * \assert
  730.  *    \code decoder != NULL \endcode
  731.  * \retval FLAC__ChannelAssignment
  732.  *    See above.
  733.  */
  734. FLAC_API FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder);
  735.  
  736. /** This is inherited from FLAC__StreamDecoder; see
  737.  *  FLAC__stream_decoder_get_bits_per_sample().
  738.  *
  739.  * \param  decoder  A decoder instance to query.
  740.  * \assert
  741.  *    \code decoder != NULL \endcode
  742.  * \retval unsigned
  743.  *    See above.
  744.  */
  745. FLAC_API unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder);
  746.  
  747. /** This is inherited from FLAC__StreamDecoder; see
  748.  *  FLAC__stream_decoder_get_sample_rate().
  749.  *
  750.  * \param  decoder  A decoder instance to query.
  751.  * \assert
  752.  *    \code decoder != NULL \endcode
  753.  * \retval unsigned
  754.  *    See above.
  755.  */
  756. FLAC_API unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder);
  757.  
  758. /** This is inherited from FLAC__StreamDecoder; see
  759.  *  FLAC__stream_decoder_get_blocksize().
  760.  *
  761.  * \param  decoder  A decoder instance to query.
  762.  * \assert
  763.  *    \code decoder != NULL \endcode
  764.  * \retval unsigned
  765.  *    See above.
  766.  */
  767. FLAC_API unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder);
  768.  
  769. /** Returns the decoder's current read position within the stream.
  770.  *  The position is the byte offset from the start of the stream.
  771.  *  Bytes before this position have been fully decoded.  Note that
  772.  *  there may still be undecoded bytes in the decoder's read FIFO.
  773.  *  The returned position is correct even after a seek.
  774.  *
  775.  * \param  decoder   A decoder instance to query.
  776.  * \param  position  Address at which to return the desired position.
  777.  * \assert
  778.  *    \code decoder != NULL \endcode
  779.  *    \code position != NULL \endcode
  780.  * \retval FLAC__bool
  781.  *    \c true if successful, \c false if there was an error from
  782.  *    the 'tell' callback.
  783.  */
  784. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_decode_position(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *position);
  785.  
  786. /** Initialize the decoder instance.
  787.  *  Should be called after FLAC__seekable_stream_decoder_new() and
  788.  *  FLAC__seekable_stream_decoder_set_*() but before any of the
  789.  *  FLAC__seekable_stream_decoder_process_*() functions.  Will set and return
  790.  *  the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK
  791.  *  if initialization succeeded.
  792.  *
  793.  * \param  decoder  An uninitialized decoder instance.
  794.  * \assert
  795.  *    \code decoder != NULL \endcode
  796.  * \retval FLAC__SeekableStreamDecoderState
  797.  *    \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
  798.  *    successful; see FLAC__SeekableStreamDecoderState for the meanings
  799.  *    of other return values.
  800.  */
  801. FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
  802.  
  803. /** Finish the decoding process.
  804.  *  Flushes the decoding buffer, releases resources, resets the decoder
  805.  *  settings to their defaults, and returns the decoder state to
  806.  *  FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
  807.  *
  808.  *  In the event of a prematurely-terminated decode, it is not strictly
  809.  *  necessary to call this immediately before
  810.  *  FLAC__seekable_stream_decoder_delete() but it is good practice to match
  811.  *  every FLAC__seekable_stream_decoder_init() with a
  812.  *  FLAC__seekable_stream_decoder_finish().
  813.  *
  814.  * \param  decoder  An uninitialized decoder instance.
  815.  * \assert
  816.  *    \code decoder != NULL \endcode
  817.  * \retval FLAC__bool
  818.  *    \c false if MD5 checking is on AND a STREAMINFO block was available
  819.  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
  820.  *    signature does not match the one computed by the decoder; else
  821.  *    \c true.
  822.  */
  823. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
  824.  
  825. /** Flush the stream input.
  826.  *  The decoder's input buffer will be cleared and the state set to
  827.  *  \c FLAC__SEEKABLE_STREAM_DECODER_OK.  This will also turn off MD5
  828.  *  checking.
  829.  *
  830.  * \param  decoder  A decoder instance.
  831.  * \assert
  832.  *    \code decoder != NULL \endcode
  833.  * \retval FLAC__bool
  834.  *    \c true if successful, else \c false if a memory allocation
  835.  *    or stream decoder error occurs.
  836.  */
  837. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder);
  838.  
  839. /** Reset the decoding process.
  840.  *  The decoder's input buffer will be cleared and the state set to
  841.  *  \c FLAC__SEEKABLE_STREAM_DECODER_OK.  This is similar to
  842.  *  FLAC__seekable_stream_decoder_finish() except that the settings are
  843.  *  preserved; there is no need to call FLAC__seekable_stream_decoder_init()
  844.  *  before decoding again.  MD5 checking will be restored to its original
  845.  *  setting.
  846.  *
  847.  * \param  decoder  A decoder instance.
  848.  * \assert
  849.  *    \code decoder != NULL \endcode
  850.  * \retval FLAC__bool
  851.  *    \c true if successful, else \c false if a memory allocation
  852.  *    or stream decoder error occurs.
  853.  */
  854. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder);
  855.  
  856. /** This is inherited from FLAC__StreamDecoder; see
  857.  *  FLAC__stream_decoder_process_single().
  858.  *
  859.  * \param  decoder  A decoder instance.
  860.  * \assert
  861.  *    \code decoder != NULL \endcode
  862.  * \retval FLAC__bool
  863.  *    See above.
  864.  */
  865. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder);
  866.  
  867. /** This is inherited from FLAC__StreamDecoder; see
  868.  *  FLAC__stream_decoder_process_until_end_of_metadata().
  869.  *
  870.  * \param  decoder  A decoder instance.
  871.  * \assert
  872.  *    \code decoder != NULL \endcode
  873.  * \retval FLAC__bool
  874.  *    See above.
  875.  */
  876. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder);
  877.  
  878. /** This is inherited from FLAC__StreamDecoder; see
  879.  *  FLAC__stream_decoder_process_until_end_of_stream().
  880.  *
  881.  * \param  decoder  A decoder instance.
  882.  * \assert
  883.  *    \code decoder != NULL \endcode
  884.  * \retval FLAC__bool
  885.  *    See above.
  886.  */
  887. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder);
  888.  
  889. /** Flush the input and seek to an absolute sample.
  890.  *  Decoding will resume at the given sample.  Note that because of
  891.  *  this, the next write callback may contain a partial block.
  892.  *
  893.  * \param  decoder  A decoder instance.
  894.  * \param  sample   The target sample number to seek to.
  895.  * \assert
  896.  *    \code decoder != NULL \endcode
  897.  * \retval FLAC__bool
  898.  *    \c true if successful, else \c false.
  899.  */
  900. FLAC_API FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
  901.  
  902. /* \} */
  903.  
  904. #ifdef __cplusplus
  905. }
  906. #endif
  907.  
  908. #endif
  909.